00. 사전 준비 (환경 설치)
00. 사전 준비: 실습 환경 설치
수업 1시간 안에 설치까지 하면 실습할 시간이 없습니다. 아래 [5. 최종 점검] 까지 마치고 오시면 됩니다.
막히는 부분은 7. 자주 나는 문제를 먼저 보시고, 그래도 안 되면 김수종 책임에게 미리 알려주세요.
준비할 것 한눈에 보기
| 순서 | 할 일 | 소요 시간 |
|---|---|---|
| 1 | Docker Hub 계정 만들기 | 3분 |
| 2 | Docker Desktop 설치 (macOS / Windows) | 10~20분 |
| 3 | Docker Desktop 로그인 · 기본 설정 | 3분 |
| 4 | 터미널 · 에디터 준비 | 5분 |
| 5 | 최종 점검 명령어 실행 | 3분 |
| 6 | 실습 이미지 미리 받아두기 | 3분 |
노트북 사양 기준
| 항목 | 최소 | 권장 |
|---|---|---|
| 메모리(RAM) | 8GB | 16GB 이상 (6주차부터 Kubernetes 노드 여러 개를 띄웁니다) |
| 디스크 여유 공간 | 20GB | 40GB 이상 |
| macOS | 최신 및 직전 2개 메이저 버전 | Apple Silicon(M 시리즈) / Intel 모두 가능 |
| Windows | Windows 10 22H2(빌드 19045) 이상 / Windows 11 23H2(빌드 22631) 이상, 64비트 | Windows 11 최신 |
1. Docker Hub 계정 만들기
Docker Hub 는 컨테이너 이미지를 올리고 내려받는 공개 저장소입니다. 앱스토어 같은 곳이라고 생각하면 됩니다.
- https://hub.docker.com 에 접속해서 Sign up 을 누릅니다.
- 개인(Personal, 무료) 계정으로 가입합니다.
- 가입한 Docker ID(사용자 이름) 를 메모해 둡니다. 4주차에 이미지를 올릴 때 씁니다.
Docker Hub 는 로그인하지 않으면 IP 하나당 6시간에 100번까지만 이미지를 받을 수 있습니다.
회의실에서는 모두 같은 인터넷(같은 공인 IP)을 쓰므로 이 100번을 참석자 전원이 나눠 쓰게 됩니다.
로그인하면 계정마다 6시간에 200번까지 받을 수 있어서 실습에 충분합니다.
2. Docker Desktop 설치
컨테이너는 원래 리눅스 커널 기능입니다. 그래서 macOS 와 Windows 에서는 바로 실행할 수 없습니다.
Docker Desktop 은 내 PC 안에 아주 가벼운 리눅스 VM 을 자동으로 띄우고, 그 안에서 컨테이너를 실행해 줍니다.
여기에 Docker 명령어 도구(CLI), Docker Compose, Kubernetes 까지 한 번에 들어 있습니다.
Docker Desktop 은 직원 250명 미만, 그리고 연 매출 1,000만 달러 미만인 회사라면 무료로 쓸 수 있습니다. 우리 회사는 여기에 해당합니다.
2-1. macOS
방법 A. 설치 파일 (권장)
- https://docs.docker.com/desktop/setup/install/mac-install/ 에 접속합니다.
- 내 Mac 칩에 맞는 파일을 받습니다.
- 확인 방법: 화면 왼쪽 위 메뉴 → 이 Mac에 관하여 → "칩" 항목
Apple M1/M2/M3/M4…→ Docker Desktop for Mac with Apple siliconIntel→ Docker Desktop for Mac with Intel chip
- 받은
Docker.dmg를 열고, Docker 아이콘을 Applications(응용 프로그램) 폴더로 끌어다 놓습니다. - 응용 프로그램에서 Docker 를 실행합니다.
- 약관(Subscription Service Agreement) 화면에서 Accept 를 누릅니다.
- 설정 화면이 나오면 Use recommended settings 를 선택하고 계속 진행합니다. 관리자 암호를 물어볼 수 있습니다.
방법 B. Homebrew 를 쓰는 분
brew install --cask docker-desktop
설치가 끝나면 응용 프로그램에서 Docker 를 한 번 실행하고, 약관에 동의해 주세요.
Rosetta 2 를 설치해 두면, 인텔(amd64)용 도구가 필요할 때 문제가 줄어듭니다.
softwareupdate --install-rosetta --agree-to-license
2-2. Windows
① WSL 2 준비 (Docker Desktop 은 WSL 2 위에서 리눅스를 돌립니다)
PowerShell 을 관리자 권한으로 엽니다(시작 메뉴 → "PowerShell" 우클릭 → 관리자 권한으로 실행).
# WSL 이 없으면 설치, 있으면 그대로 진행됩니다
wsl --install --no-distribution
# WSL 을 최신으로 업데이트
wsl --update
# 버전 확인: "WSL 버전" 이 2.1.5 이상이면 OK
wsl --version
출력 예시:
WSL 버전: 2.6.3.0
커널 버전: 6.6.87.2-1
...
wsl --install 을 처음 실행했다면PC 를 재부팅한 뒤 다음 단계로 넘어가세요.
② Docker Desktop 설치
- https://docs.docker.com/desktop/setup/install/windows-install/ 에서 Docker Desktop for Windows - x86_64 를 받습니다.
- ARM 노트북(Snapdragon 등)이라면 Arm (Early Access) 버전을 받습니다. 아직 시험판이라 문제가 생기면 알려주세요.
Docker Desktop Installer.exe를 실행합니다.- 설치 옵션은 기본값 그대로 둡니다.
- 설치 방식은 사용자 단위 설치(Per-user) 가 기본이라 관리자 권한이 필요 없습니다.
- 백엔드는 WSL 2 를 사용합니다.
- 설치가 끝나면 Close 를 누르고, 시작 메뉴에서 Docker Desktop 을 실행합니다.
- 약관 화면에서 Accept 를 누릅니다.
winget install -e --id Docker.DockerDesktop
설치 중에 관리자 권한(UAC) 창이 뜨면 예를 누르세요.
실습 전에 시작 메뉴에서 Docker Desktop 을 직접 실행하세요.
작업 표시줄 오른쪽 아래에 고래 아이콘이 보이고, 대시보드 왼쪽 아래에 Engine running 이 보이면 준비된 것입니다.
3. Docker Desktop 로그인 · 기본 설정
3-1. 로그인 (macOS / Windows 동일)
- Docker Desktop 오른쪽 위의 Sign in 을 누릅니다.
- 브라우저가 열리면 1단계에서 만든 계정으로 로그인합니다.
- Docker Desktop 오른쪽 위에 내 아이디가 보이면 완료입니다.
- Docker Hub pull 제한이 IP 공용 한도가 아니라 내 계정 기준(6시간에 200회) 으로 바뀝니다.
- 4주차에 내가 만든 이미지를 Docker Hub 에 올릴(push) 때도 로그인이 필요합니다.
3-2. 메모리 할당 확인
6주차부터 Kubernetes 를 띄우면 메모리를 꽤 씁니다. 지금은 확인만 해 두세요.
| OS | 확인 위치 | 권장 |
|---|---|---|
| macOS | Docker Desktop → Settings(⚙️) → Resources → Memory | 노트북 RAM 의 절반 정도 (16GB 노트북이면 8GB) |
| Windows (WSL 2) | 따로 설정하지 않아도 됩니다. 기본으로 PC 메모리의 50% 까지 사용합니다. | 기본값 유지 |
4. 터미널 · 에디터 준비
4-1. 터미널
| OS | 사용할 터미널 | 주의 |
|---|---|---|
| macOS | 기본 터미널 앱 (또는 iTerm2). 셸은 zsh | - |
| Windows | PowerShell (Windows Terminal 안의 PowerShell 도 OK) | Git Bash 는 쓰지 마세요 |
Git Bash 는 /etc/os-release 같은 리눅스 경로를 Windows 경로로 몰래 바꿔서 Docker 에 넘깁니다.
$ docker run --rm alpine:3.24 cat /etc/os-release
cat: can't open 'C:/Program Files/Git/etc/os-release': No such file or directory
PowerShell 에서는 이런 문제가 없습니다. 이 스터디의 Windows 명령어는 모두 PowerShell 기준입니다.
4-2. 에디터: VS Code (권장)
- https://code.visualstudio.com 에서 설치합니다.
- 왼쪽 확장(Extensions) 메뉴에서 아래 두 개를 설치합니다.
| 확장 이름 | 만든 곳 | 용도 |
|---|---|---|
| Container Tools | Microsoft | 컨테이너 · 이미지 목록 보기, Dockerfile 자동완성 |
| Docker DX | Docker | Dockerfile · Compose 파일 오류 검사 |
6주차에 Kubernetes 확장을 추가로 안내합니다.
5. 최종 점검
터미널(macOS: 터미널 / Windows: PowerShell)을 열고 아래 명령어를 하나씩 실행합니다.
5-1. 버전 확인
docker version
출력 예시: Client 와 Server 가 둘 다 나와야 정상입니다.
Client:
Version: 29.8.1
...
Server: Docker Desktop 4.93.0 (240920)
Engine:
Version: 29.8.1
...
Server 부분에 에러가 나온다면
failed to connect to the docker API ... 같은 메시지가 보이면 Docker Desktop 이 실행되지 않은 상태입니다. Docker Desktop 을 실행하고 1분쯤 기다린 뒤 다시 시도하세요.
docker compose version
출력 예시:
Docker Compose version v5.5.1
5-2. 첫 컨테이너 실행
docker run --rm hello-world
출력 예시: 아래 문장이 보이면 설치 성공입니다. 🎉
Hello from Docker!
This message shows that your installation appears to be working correctly.
5-3. Docker Hub 로그인 확인
docker login
- Docker Desktop 에 이미 로그인했다면 바로
Login Succeeded가 나옵니다. - 아니라면 화면에 나오는 안내(브라우저 로그인 또는 코드 입력)를 따라 로그인합니다.
6. 실습 이미지 미리 받아두기
회의실 네트워크가 몰리지 않도록 1~2주차에 쓸 이미지를 미리 받아 둡니다.
docker pull hello-world
docker pull alpine:3.24
docker pull ubuntu:26.04
docker pull nginx:1.30-alpine
받은 이미지를 확인합니다.
docker image ls
출력 예시:
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
alpine:3.24 294b683cb724 13MB 3.94MB
hello-world:latest 5e2309035332 25.9kB 9.49kB
nginx:1.30-alpine 0985e772fb9f 93.6MB 27MB
ubuntu:26.04 da6fc2be5478 160MB 45.3MB
ID 와 용량은 사람마다 조금 다를 수 있습니다. 4개가 모두 보이면 준비 끝입니다. ✅
7. 자주 나는 문제와 해결
공통
| 증상 | 원인 | 해결 |
|---|---|---|
failed to connect to the docker API |
Docker Desktop 이 꺼져 있음 | Docker Desktop 실행 후 Engine running 확인 |
toomanyrequests: You have reached your pull rate limit |
Docker Hub 비로그인 상태로 너무 많이 받음 | 3-1. 로그인 후 다시 시도 |
Bind for 0.0.0.0:8080 failed: port is already allocated |
다른 프로그램이 같은 포트를 쓰는 중 | 1주차에서 설명합니다. 다른 포트 번호(예: 8081)를 쓰면 됩니다 |
Windows
| 증상 | 해결 |
|---|---|
| 설치 중 "WSL 2 is not installed" / "WSL update required" | 관리자 PowerShell 에서 wsl --update 실행 후 재부팅 |
| "Virtualization support not detected" | BIOS/UEFI 에서 가상화(Intel VT-x / AMD-V, SVM) 를 켜야 합니다. 노트북마다 메뉴가 다르니 문의해 주세요 |
| 업데이트 후 "WSL integration with distro 'Ubuntu' unexpectedly stopped" 창이 계속 뜸 | 아래 순서대로 하세요 ⬇️ |
WSL integration 오류가 반복될 때 (실제로 겪고 해결한 방법)
# 1) 작업 표시줄의 고래 아이콘 우클릭 → Quit Docker Desktop 으로 완전히 종료
# 2) WSL 을 완전히 내림 (열려 있는 Ubuntu 창이 있으면 같이 닫힙니다)
wsl --shutdown
# 3) 시작 메뉴에서 Docker Desktop 다시 실행
Ubuntu 같은 WSL 배포판을 쓰지 않는다면, 창의 Skip WSL distro integration 을 눌러도 이 스터디 실습에는 지장이 없습니다.
macOS
| 증상 | 해결 |
|---|---|
docker: command not found |
Docker Desktop 을 한 번도 실행하지 않은 경우입니다. 응용 프로그램에서 Docker 를 실행하고 약관에 동의하세요 |
| Docker Desktop 이 멈춘 듯 시작이 안 됨 | 메뉴 막대 고래 아이콘 → Troubleshoot → Restart Docker Desktop |
참고 자료
공식 문서:
- Docker Desktop for Mac 설치: https://docs.docker.com/desktop/setup/install/mac-install/
- Docker Desktop for Windows 설치: https://docs.docker.com/desktop/setup/install/windows-install/
- Docker Hub pull 제한: https://docs.docker.com/docker-hub/usage/pulls/
네비게이션
| 목록 | 다음 |
|---|---|
| 목록으로 | 1주차 강의 노트 ▶ |